<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 
Transitional//EN">
<html>
<head>
  <title>Introduction to 
SPICE</title>
</head>
<body style="color: rgb(0, 0, 0); 
background-color: rgb(255, 255, 255);">
<table
 style="text-align: 
left; margin-left: auto; margin-right: auto; width: 800px;"
 
border="0" cellpadding="5" cellspacing="2">
  <tbody>
    <tr>
 
<td
 style="background-color: rgb(153, 153, 153); vertical-align: 
middle; text-align: center;">
      <div 
align="right"><small><small><a 
href="../index.html">Main
Page</a></small></small> </div>
 
<b>Introduction to SPICE</b> </td>
    </tr>
    <tr>
      <td 
style="vertical-align: top;">
      <div style="text-align: right;">
 
<pre>29-Feb-2008</pre>
      </div>
      <h1> Welcome to SPICE</h1>
 
<p>Welcome to SPICE, an ancillary information system that
provides 
scientists and engineers the capability to include space geometry and 
event data
into mission design, science observation planning, and 
science data
analysis software.  </p>

<p>The principle components of 
the SPICE system are SPICE Toolkit software and SPICE
data 
files&#8212often called "kernels."<p>


   
<p>SPICE is used 
throughout NASA and within many other U.S. and international agencies 
for
organizing, distributing, and accessing ancillary data associated 
with space science
missions.  The NAIF website contains the few <a 
href="http://naif.jpl.nasa.gov/naif/rules.html">  
important rules 
</a> regarding using SPICE. Please take a moment to read these.</p>
 

 <br>    
      <h1>Using SPICE Toolkit Software</h1>

<p>Your first 
step is to <a href="http://naif.jpl.nasa.gov/naif/toolkit.html"> 

download a SPICE Toolkit package </a>from the NAIF website if 
a
current version is not already installed on your machine or 
available through some
form of connected server. In addition to the 
Toolkit download package and installation
script you will find 
several important documents.

      <p>The README file provides 
installation instructions.

      <p>The Description document 
(dscriptn.txt) provides an
overview of the contents and organization 
of the Toolkit.<br>
      </p>
      
      <p>The What's New 
document (whats.new)
describes new and changed capabilities of this 
Toolkit as regards
previous versions, and lists the supported 
environments 
(environment = language/platform/OS/compiler) for 
the
Toolkit.<br>
      </p>

     
      <h2> What Else is 
Needed</h2>
      
      <p>Use of the SPICE system requires (at a 
minimum) one
of the following: a
FORTRAN 77 compiler/linker, an ANSI 
C compiler/linker, an IDL
installation, or a MATLAB installation, 
that is consistent with the components
NAIF used in building the 
Toolkit you have downloaded. You'll also need a
text 
editor&#8212preferably one that is familiar to you and perhaps that 

is good for writing code. Familiarity with a debugger can
also be 
helpful
as you develop your application program. You will need to 
know
how to build and execute a program on your computer.</p>

 
<h2>Getting Started</h2>
   
NAIF provides a variety of aids to help 
you begin using SPICE. Make
good use of 
these.

<h3>Tutorials</h3>

NAIF offers a large set of tutorials, 
provided in viewgraph style.
Individual tutorials, or the entire 
package, may be 
<a 
href="http://naif.jpl.nasa.gov/naif/tutorials.html">downloaded</a>
from 
the NAIF website. These tutorials are listed pretty much in the 
order
a beginner might wish to follow. However we especially 
encourage a new
SPICE user to look through "conventions" through 
"intro to toolkit," and 
also "common_problems" and "summary of key 
points." The new user should
also look at other tutorials as 
appropriate to the task at hand; probably
this would include "time" 
and "spk" at a minimum.

<h3>Programming Examples</h3>

Three kinds 
of programming examples are available, each a little different. 
Each 
type is offered in all the languages supported by SPICE.

<ul>
<li> 
The code for several very simple SPICE-based programs is provided 
in
a set of so-called "cookbook" programs found in each copy of the 
Toolkit. The
topics covered are time conversions (tictoc), reading a 
trajectory
file (states), computing the angular separation of two 
objects as seen from
a third (simple), and computing a spacecraft's 
sub-observer point on 
a target body (subpt). The annotated source 
code, a User's Guide, and
sample data files for running these 
programs are all provided.

<p>
<li> The code for a program that 
computes a spacecraft instrument's
boresight intercept on a body's 
surface, plus the phase, incidence and
emission angles at that point 
(and a bit more) is provided in the set of
tutorials named 
"program_(language)." Here you can follow the code
development 
step-by-step.

<p>
<li> A set of <a 
href="ftp://naif.jpl.nasa.gov/pub/naif/toolkit_docs/Lessons">
"open 
book" programming lessons</a> is available from the NAIF server. 
These
are used in the annual SPICE Training classes taught by NAIF 
staff, but you
can do them on your own. Each lesson comes with a 
problem statement including
a graphic that depicts the problem, a set 
of notes and tips about how to
create the desired program, a list of 
the SPICE data files (kernels) to be
used, and the actual code 
solution created by a NAIF staff member. The kernels
needed to run 
the programs are also provided, and the answers obtained from 
the
completed NAIF-written version of the program is shown at the 
end. Each lesson
is broken into manageable chunks, with the 
intermediate answers provided. The
primary lessons 
are:
<p>
<ul>
<li>Toolkit Contents &#160(practice navigating through 
the Toolkit components)
<li>Starting Programming &#160(demonstrating 
you can compile and link a program)
<li>Remote Sensing &#160(a 
realistic space geometry task for a remote sensing 
instrument)
<li>Other Stuff &#160(a collection of small, independent 
tasks)
</ul>
<p>
Additional lessons are:
<ul>
<li>Insitu Sensing 
&#160(a realistic space geometry task for an in-situ 
instrument)
<li>Event Finding &#160(a more difficult lesson involving 
visibility calculations
in the face of 
occultations)
</ul>
</ul>
<p>
In addition to the training code 
described above, nearly every API (subroutine)
contains one or more 
example code fragments showing samples of how that
particular routine 
might be used in a typical problem. These examples
are contained in 
the header of the module. The html versions of Toolkit 
documentation 
contain hyperlinks to these headers, or you may open the
source code 
module in an editor or with a text display utility.


 
<h3>Finding the Appropriate Routine </h3>
      <p>The real 
programming power of SPICE derives from the extensive
set of built in 
computations you need not re-invent. However, as the
Toolkits contain 
hundreds of routines, reading all routine
headers or API descriptions 
to determine the
appropriate routine for a given task is not 
practical. In addition to numerous 
API references
in the tutorials 
mentioned earlier, NAIF provides two products in each
Toolkit to help 
you find an API that may meet your needs.
<ol>
<li> A permuted index 
may help you identify the
proper routine based on functionality 
statements. Since the index is
permuted, any of a series of short 
phrases you may think of to describe a
computation you need might be 
found in the permuted index document,
pointing to a relevant routine. 
For example you will find </p>
      <pre>   Cross product of two 
vectors<br><br>   Product of two vectors, cross<br><br>   Vectors, 
cross product of two<br></pre>
all listed in the permuted index. Each 
of these points to the SPICELIB
subroutine VCRSS, or the CSPICE 
function vcrss_c, that computes a cross
product. Using the 
hyperlinking within this document you can click on the 
API
(subroutine or function) name to bring up the source code header 
for that module. In
this header you will find the detailed 
specifications and examples needed to
decide if the module does 
indeed provide the computation you sought.

<p> The permuted index is 
found in the /doc/html/info folder and is named
spicelib.idx in 
FORTRAN toolkits and cspice_idx in CSPICE, Icy and 
Mice 
Toolkits.

<li>A document named "Most Used APIs" provides a 
brief
summary of the purpose and use of the most used 
(high-level)
APIs. The document is organized by functional 
categories, such as:
<p>
<ul>
<li> time system conversions
<li> 
positions of spacecraft and natural bodies
<li> orientation of 
spacecraft and instruments
<li> reference frame transformations
<li> 
illumination angles
</ul>
<p>and so on. The "Most Used APIs" document 
is found in the /doc/html/info folder of
each Toolkit.
</ol>

<br>

 
<h1>SPICE Kernels </h1>
      <p>SPICE stores data in files that are 
often referred to as "kernels.'' A
kernel may store data in either 
text (ASCII) or binary format. In order to access data
within a 
kernel
an application program must "load" the kernel using a SPICE 
API ("furnsh").</p>

<p>Excepting the important platform-specific 
differences mentioned below, any
particular kernel may be used with 
any of the Toolkits. 



<h2>Text Kernels</h2>
      <p> The set
of 
text kernels consists of:<br>
      </p>
      <ul>
 
<li>Spacecraft Clock kernels (SCLK)</li>
        <li>Leapseconds 
kernel (LSK)</li>
        <li>Text-style (most) Physical Constants 
kernels (PCK)</li>
        <li>Instrument parameter kernels 
(IK)</li>
        <li>Frame definition kernels (FK)</li>
 
<li>Some E-kernels (EK, although EKs are now rarely used)</li>
 
<li>Meta-kernels (MK, also called "furnsh kernels")</li>
      </ul>
 
<p>As for any text file, a SPICE text kernel contains operating 
system 
      specific line terminators. Trying to use a non-native 
style text kernel is
      one of the most prevalent user errors. To 
mitigate this problem somewhat the
CSPICE, Icy, and Mice Toolkits 
include code that allows reading of
non-native text kernels. 
Unfortunately this accommodation is <b>not</b> possible
in the 
FORTRAN Toolkits because the FORTRAN language does not allow 
detection of 
C-style line terminations. FORTRAN Toolkits contain 
code that will issue a SPICE
error message whenever a non-native text 
kernel load occurs.<br>
      </p>
      
      <h2>Binary 
Kernels</h2>
      
      <p> The set of binary kernels consists of: 
</p>
      
      <ul>
        <li>SP-kernels (SPK)</li>
 
<li>Binary-style (just a few) PC-kernels (PCK)</li>
 
<li>C-kernels (CK) </li>
        <li>Some spacecraft Events kernels 
(EK/ESP) </li>
      </ul>
      
      <p> Binary kernels typically 
contain numeric and textual information.
 Hardware architecture (the 
CPU chip)
determines the format of numeric binary data; the two 

formats used by computers supported by NAIF are called "big endian" 
and "little
endian." Because kernels are frequently transferred 
between computers which may use
incompatible binary architecture, 
SPICE software has been designed to read
non-native binary kernels. 
(But not to write to a non-native binary kernel.)
   
   <h2>Loading 
Kernels</h2>   
      
      <p>One "loads" kernels to give the SPICE 
system the information
needed to
find the data within the kernels. 
The tutorial named "intro to kernels" quickly
describes the loading 
process. The Kernel Required Reading document (<a
 href="../req/kernel.html" 
target="_blank">kernel.req</a>) provides a complete description. 
 
Examples of loading kernels may be seen in the cookbook programs and 
the "open book"
programming lessons previously mentioned.
Except for 
unusual circumstances, kernels of all types need "loading"
only once 
in your program&#8212do not embed the load statement in a loop.<br>
 
</p>


      <h2>Creating or Modifying Kernels</h2>
      
<p>The 
majority of SPICE users will not need to create or modify kernels. 
But if
you do need to do so you must do so carefully to avoid 
structural problems and to
help ensure others will easily use the 
kernel. Careful testing of a kernel you
create, and of the kernel 
production process for binary kernels, is essential!

<h3>Creating or 
Modifying Text Kernels</h3>

Because they are just text files, text 
kernels are created or modified with any 
text editor.
Although the 
format of these files appears fairly easy to deduce, we
recommend you 
consult the document <a href="../req/kernel.html"
 target="_blank">kernel.req</a> 
before you attempt to create or
edit any text kernel for the first 
time. You should also review the tutorial
created for the kind of 
text kernel with which you will be working.</p>

    <h3>Creating or 
Modifying Binary Kernels</h3>

<p> Some SPICE users will want to 
create or modify binary kernels. This
task requires a good 
understanding of the particular SPICE kernel type, and of
the 
appropriate binary kernel writer API(s).  You should be familiar with 
the
tutorial discussing the kernel type of interest. NAIF recommends 
you also
read the "Making an SPK" or the "Making a CK" tutorial, if 
relevant.
You should also read appropriate portions of the "required 
reading" 
reference document pertinent to your
task (<a 
href="../req/spk.html" target="_blank">spk.req</a>, <a href="../req/ck.html"
 
target="_blank">ck.req</a>, <a href="../req/pck.html" 
target="_blank">pck.req</a>
or <a href="../req/ek.html" 
target="_blank">ek.req</a>).

  <h3>Annotating a New or Modified 
Kernel</h3>
Whenever you create or modify a kernel you have the 
responsibility to properly and
thoroughly annotate that kernel so 
that users of it (including yourself) can understand
why, when and 
how it was made. This annotation process is called adding comments 

(or adding meta-data). Both text and binary kernels can accommodate 
such comments. The
tutorial named "introduction to kernels" provides 
some information about this.

<p> Comments (metadata) are added to 
text kernels using any text editor, just as for
making or modifying 
the data sections of the text kernel.

<p> Comments (metadata) are 
normally added to, extracted from, or removed from a binary
kernel 
using a Toolkit utility program named "commnt."


      <h2> 
Selecting and Obtaining Kernels </h2>

<p>Knowing which kernel, or 
set of kernels, to use in any particular task can be a
challenge. 
Having kernel producers use a consistent and well
thought out kernel 
naming methodology is a must. Having kernel producers provide high 

quality metadata with each kernel or kernel collection is equally 
important.
Nevertheless, kernel selection is one of the most 
challenging aspect of using the
SPICE system. (Probably the same 
challenge would exist no matter what kind of
ancillary information 
system would be used.)

<p> Often three classes of kernels are 
available:
<ul>
<li>mission operations kernels
<li>mission archived 
kernels
<li>generic kernels
</ul>

<p><b>Mission operations 
kernels</b> are those produced before or while a spacecraft 
is
operating, to support science observation planning, initial 
science data processing
and analysis, and mission engineering 
functions. There are often many of these kernels.
Those types that 
provide data as a function of time&#8212especially SPK and 
CK&#8212may
have many overlaps in time. Some may be "predict" 
versions made for observation
planning while others may be 
"reconstruction" versions made for science data processing.
Selecting 
kernels from this class can be quite a challenge, especially if you 
are not
a regular consumer of mission operations 
kernels.

<p>Certainly for NASA planetary missions, and probably for 
missions operated by other
agencies, <b>mission archived kernels</b> 
are usually your best bet&#8212if there are 
already archived kernels 
covering the period of the mission of interest to you.
A mission's 
archived kernels are usually better organized and documented, and 
often
sets of "small" kernels covering short periods of time have 
been merged into more
easily used "large" kernels covering a longer 
time span.

<p>For JPL-managed missions the <b>mission archived 
kernels</b> often have associated
"furnsh" kernels (meta-kernels) 
that logically aggregate the entire collection of kernels
appropriate 
for a given time span or a given mission phase. Make use of 
these!

<p>Be aware that for all but the shortest missions the 
archiving of SPICE data is
usually done in increments, with a new 
batch of data added to the collection on
a regular 
basis&#8212typically every three or six months. The usual (preferred) 
NAIF
methodology for archiving SPICE data is to create a single, 
"accumulating" 
SPICE dataset. Every few months the next batch of 
kernels is added to the existing
dataset, with updates made to the 
dataset's metadata indicating the new (longer) 
time span covered by 
the whole collection.

<p><b>Generic kernels</b> are those that are 
not tied specifically to one mission; they are
usually applicable to 
many missions, or could be useful independent of any mission. 
Examples
of generic kernels are:
<ul>
<li> the planetary, satellite, 
comet and asteroid ephemeris files produced by JPL (SPKs)
<li> the 
leapseconds kernel (LSK)
<li> the "generic" version of the planetary 
constants kernel (text PCK)
<li> the high-precision lunar orientation 
kernel (binary PCK)
<li> earth station topocentric locations (SPK) 
and reference frames (FK)
<li> various kinds of mission-independent 
reference frame specifications (FK)
</ul>
<p>A majority of the 
generic kernels are produced by NAIF and made available from 
the
generic kernels link on the <a 
href="http://naif.jpl.nasa.gov/naif/data.html">Data webpage.</a>
But, 
as the use of SPICE spreads, other agencies may also offer generic 
kernels.



<p>Since you probably won't produce your own kernels, you 
need to
obtain them from someplace&#8212normally a project database 
or project data
management team. Once a mission is complete the 
kernels should be
available from a national data archive center. The 
NAIF node of the
Planetary Data System is one such example (<a
 
href="http://naif.jpl.nasa.gov/naif/data.html">http://naif.jpl.nasa.gov/naif/data.html</a>).<br>
 
</p>


<br>
      <h1>Troubleshooting Options<br>
      </h1>
 
<p>With any new product people sometimes encounter problems. If
you 
run into problems, here are some steps you can take to try to
resolve 
them. </p>
      <ul>
         <li> A tutorial named "common 
problems" is available from the NAIF
         website; take a look at 
this.
         <li> Several of the subsystem tutorials (for example 
SPK and CK)
         contain a discussion of common problems at the 
end of the tutorial;
         check these out.

        <li> All 
Toolkit distributions include a document named <a
 
href="../req/problems.html" target="_blank">problems.req</a> in the /doc 
folder, and
 in the /doc/html folder. This document lists the 
most
common problems and aggravations the new SPICE user might 
experience,
and the most probable solutions. </li>
        <li> If 
you think the problem is related to a SPICE routine,
look
at the 
reference documents related to the routine&#8212these are listed in 
the
required reading section of the routine's header. These documents 
may
contain useful information for diagnosing and correcting the 
problem. </li>
        <li> If the problem seems related to your 
programming
environment,
(for example you can't link a program, can't 
find a file, don't have
sufficient privileges to perform some action, 
etc.) contact your system
manager. She/He may be able to assist you.
 
<li> If you are using either the Icy (IDL) or Mice (MATLAB) version
 
of SPICE be sure to read the environment configuration information
 
for these two products provided in the "Preparing for Programming" 
tutorial.
        </li>
        <li> If you are using a SPICE based 
program developed by someone
else, contact that program's author for 
assistance. </li>
        <li> If your program executes but your 
output disagrees with
those of a colleague who supposedly ran the 
same program with identical
inputs, ensure you both used the same 
kernel files. </li>
        <li> If you don't have the latest version 
of a kernel
associated with a flight project (or want to find out if 
you do)
contact the project's SPICE data administrator. </li>
 
<li> If you can't seem to fit the problem into one of the 
above
categories, or just aren't getting anywhere, send us (NAIF) 
e-mail or
call us on the phone; we'll do what we can to help within 
our
resources and programmatic limitations. See the <a 
href="http://naif.jpl.nasa.gov/naif/gettinghelp.html">
getting 
help</a> link on the NAIF webpage.</li>
      </ul>

<br>
      
 
<h1> SPICE Software Quality andStability</h1>
      <p>NAIF is 
committed to providing a robust, flexible, and
understandable product 
that suits the needs of the space science
community. SPICE Toolkit 
software undergoes considerable review and
testing; the documentation 
for the SPICE software is extensive and
(usually) accurate. </p>
 

      <p> The SPICE system is undergoing continuous development to 
 
both improve existing capabilities and to add new ones. However,
NAIF 
is committed to providing SPICE users a consistent
product. We 
understand the frustrations of using a set of software only
to see it 
change in a subsequent release. Therefore, we do not
change the 
intended functionality of, or the interface to, previously
released 
software unless needed to correct a bug, or
occasionally to improve 
an implementation. If
you build a program incorporating
today's SPICE 
system, it should work the same way when you
re-build it
with 
tomorrow's SPICE system. Retaining backwards compatibility is a 

primary development objective within NAIF.
      </p>

<br>
      
 
<h1>SPICE Data Accuracy</h1>

The SPICE ancillary information system 
might be thought of as a collection of
flexible "data buckets" 
accompanied by means to place data into those buckets and
means to 
extract data from the buckets and construct something useful from 
those data.
The data placed into those "buckets" is obtained from 
sources external to SPICE.

<p>In some cases the source data are 
transformed ("manipulated") before or being
placed or as they are 
placed inside a kernel file. In most cases the data extracted 
from a 
kernel are transformed by the Toolkit application program interfaces 
(APIs, 
sometimes referred to in SPICE documentation as subroutines) 
SPICE customers use to 
compute the observation geometry parameters 
of interest&#8212position, range, 
LAT/LON, lighting angles, 
etc.

<p>One can see there are several possible contributors to the 
accuracy of geometry 
parameters computed using SPICE. (The situation 
may be quite similar when using means
other than SPICE to make the 
same kinds of computations.) One cannot make an assessment
of 
accuracy that applies to all SPICE-based results. In many cases the 
accuracy of
a high-level geometry parameter determined using SPICE is 
principally determined by the
accuracy of the source data used to 
make a kernel&#8212"garbage in, garbage out" applies.
 In some cases 
the accuracy is 
somewhat or even highly dependant on the kernel 
producer's knowledge of the dynamics or
timing of the physical 
system
involved and his/her skill in using kernel production 
software. (This is often the case for
production of SPKs, CKs, and 
SCLKs.)

<p>Because of the complexity of determining data accuracy, 
especially for time-dependent data,
and also because of the 
complexity of processing any such data within SPICE, the SPICE 
system
provides no numerical mechanisms for managing accuracy 
information. The only provision
for dealing with accuracy information 
in SPICE is the ability of each kernel type to contain
text 
"comments" (meta-data) provided by the kernel producer that state 
whatever that producer
feels is relevant about the accuracy of data 
that may be extracted from the kernel. The user of
the kernel can see 
(read) any such comments and decide what if anything to do with that 
information.
That said, because it is often difficult for a kernel 
producer to confidently determine the accuracy
of source data, it is 
rare that useful accuracy information is placed in a 
kernel.</p>

<br>      
      
      <h1> Please Share Your Opinion 
</h1>
      <p>The NAIF Team encourages SPICE users to comment on 
the
SPICE system. If you like what you've received, let us know. 
If
some part of the system fails, or performs in an unexpected 
manner,
tell us that too. </p>
      <p> If you have ideas for 
improvements or enhancements, we'd like
to hear about them. With the 
support and suggestions of users, the
SPICE system will continue as a 
valuable resource for the space science
community for decades to 
come. </p>

<br>

<h1>Stay Connected</h1>
      <p>If you wish to keep 
well informed about SPICE related news, 
      consider signing up 
with the
      <a 
href="http://naif.jpl.nasa.gov/mailman/listinfo/spice_announce">
 
spice_announce</a> Mailman system. </p>
      </td>
    </tr>
 
</tbody>
</table>
</body>
</html>
